Add opt-in versioned row publication mode - #186

Summary

• add an opt-in versioned-row-publication mode for generated reads that overlap row mutation
• publish immutable Arc<Row> versions while retaining archived pages as the persistence/mutation image
• stage inserts as ghosted, publish only after index installation, and hide deleted versions
• add a read-side grace period so delete/vacuum cannot reuse a physical link captured by an in-flight generated read
• make primary/unique point reads retry a replacement-link swing and revalidate point/range predicates
• serialize internal archived-page access in this mode; the default low-latency path is unchanged
• use a feature-only lock-protected hash registry keyed by normalized physical offsets for publication metadata

This draft is stacked on #185 because it includes the unique point-read predicate revalidation from that PR.

Contract

With the feature enabled, generated reads return a complete old or new owned row version and never deserialize concurrently-mutated archived bytes. Insert ghosts and deleted rows are not returned, and retired links/pages are not reused until pre-existing generated readers drain.

This is not MVCC or a snapshot-isolation implementation. Range scans may include or omit rows changed during the scan. The guarantee excludes callers that bypass generated table methods and directly mutate low-level Data pages. Point-read retry may starve under perpetual replacement churn.

The protocol and scope are documented in docs/versioned-row-publication.md.

Validation

• cargo test --all-targets: 115 unit tests and 326 active integration tests passed (5 ignored)
• cargo test --all-targets --features versioned-row-publication: 119 unit tests and 328 active integration tests passed (5 ignored)
• the concurrent unique-read/reinsert regression passed in five additional repeated runs
• cargo clippy --all-targets -- -D warnings
• cargo clippy --all-targets --features versioned-row-publication -- -D warnings
• cargo fmt --all -- --check

Feature-only deterministic tests cover incomplete multi-field page mutation, ghost visibility, retired-version lifetime, physical-link ABA prevention, and integer/float range predicate revalidation.

Performance

Five alternating Criterion runs per mode on Darwin arm64, 20 samples/run, 0.2 s warmup, and 0.5 s measurement. The one-row range result uses seven alternating runs, 25 samples/run, 0.3 s warmup, and 0.7 s measurement after a shorter run showed excess variance.

Replacing the ordered publication index with the offset-keyed registry reduced the feature-on primary read from 96.811 ns to 61.058 ns and the feature-on unique read from 92.974 ns to 66.339 ns. Seven direct paired old/new runs also measured the optimized unique-index update 2.09% faster than the prior PR implementation. Read-only scaling and 2/4/8-writer contention checks showed no regression from the registry change.

The remaining feature-on cost is still material for latency-sensitive deployments. The feature remains off by default; feature-off point/read/write differences are at or below 1.02% in the final set.

Before merge

• quantify live-row and retirement-queue memory overhead on representative schemas
• model-check the grace-period/replacement protocol and add longer adversarial stress runs
• decide whether point-read retry needs a documented bound
• measure mixed read/write scaling on representative production hardware
• reconcile this design with the global-barrier fallback in feat: gate synchronized page access #183 and the epoch-vacuum work in fix: replace vacuum delay with epoch grace period #184